home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Magnum One
/
Magnum One (Mid-American Digital) (Disc Manufacturing).iso
/
d10
/
rem23.arc
/
REMIND.DOC
< prev
next >
Wrap
Text File
|
1991-02-19
|
48KB
|
1,258 lines
REMIND 2.3 #0
By David Skoll
(C) 1990, 1991 by David Skoll
19 February 1991
To print this document, type: COPY REMIND.DOC PRN
Table of Contents
1. INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . 1
2. THE FINE PRINT . . . . . . . . . . . . . . . . . . . . . . 2
3. USING REMIND . . . . . . . . . . . . . . . . . . . . . . . 3
3.1. Running REMIND . . . . . . . . . . . . . . . . . . . 3
3.2. The REM Command . . . . . . . . . . . . . . . . . . 4
3.2.1. Date specifications . . . . . . . . . . . . . 5
3.2.2. Backward Scanning . . . . . . . . . . . . . . 7
3.2.3. Advance Warning . . . . . . . . . . . . . . . 7
3.2.4. The MSG Keyword . . . . . . . . . . . . . . . 8
3.2.5. The RUN Keyword . . . . . . . . . . . . . . . 8
3.2.6. Getting Reminded only Once per Day . . . . . 8
3.2.7. Locally Omitting Weekdays . . . . . . . . . . 9
3.2.8. Periodic Reminders . . . . . . . . . . . . . 9
3.2.9. The AT Keyword . . . . . . . . . . . . . . . 10
3.2.10. The BEFORE, SKIP and AFTER Keywords . . . . 10
3.3. The OMIT Command . . . . . . . . . . . . . . . . . . 11
3.3.1. The "+" and "-" Forms vs "++" and "--" . . . 12
3.4. The UNTIL Keyword . . . . . . . . . . . . . . . . . 12
3.5. The INCLUDE Command . . . . . . . . . . . . . . . . 13
3.6. Substitution . . . . . . . . . . . . . . . . . . . . 13
3.7. Producing a Calendar . . . . . . . . . . . . . . . . 17
3.8. The BANNER Command . . . . . . . . . . . . . . . . . 17
3.9. Controlling the OMIT Context . . . . . . . . . . . . 18
4. PURGING REMINDER FILES . . . . . . . . . . . . . . . . . . 19
5. DEBUGGING YOUR REMINDER FILE . . . . . . . . . . . . . . . 19
5.1. Format of Debugging and Error Messages . . . . . . . 19
6. WISH LIST . . . . . . . . . . . . . . . . . . . . . . . . . 20
7. WISHES LIST . . . . . . . . . . . . . . . . . . . . . . . . 20
REMIND 2.3.0 (19 February 1991) Page i
1. INTRODUCTION
REMIND version 2.3 is an advanced reminder program. It is similar
to the Unix "calendar" program, only much more versatile and with
enhanced features.
REMIND reads a text file (which you create) containing a list of
commands. Most of these commands are "reminders" which are issued
whenever the current date meets specified criteria. The reminders
can print a message to the console or run a program.
Some features of REMIND include the following:
o Ability to issue a reminder any number of days in advance
o Ability to skip holidays and weekends when reminding in
advance
o Ability to include standard files for system-wide reminders
or standard sets of holidays
o Advanced date calculation
o Ability to run a program rather than display a message when a
reminder is issued
o Ability to purge reminder file to remove obsolete reminders
o Ability to create a calendar with your reminders
automatically filled in on the appropriate dates
REMIND 2.3.0 (19 February 1991) Page 1
2. THE FINE PRINT
REMIND is yours to keep, use, distribute and enjoy. However,
there are some things you can't do:
i) You can't claim that you (or anyone other than I) wrote
REMIND.
ii) You can't distribute REMIND for profit.
iii) You can't distribute a modified version of REMIND, or a
version of REMIND which is missing this document.
REMIND is copyright (C) 1990, 1991 by David Skoll.
If you wish to support the creation of software like REMIND, you
can send me a donation. Any amount would be appreciated; the
suggested amount is $18. Note that this is strictly voluntary. If
you don't make a donation, you don't suffer any penalties. If you
make a donation, you don't get any special service for it. But
you will have helped support the creation of useful and
reasonably-priced software.
My mailing address is:
David Skoll
4-317 LeBreton Street
Ottawa, Ontario
K1S 4L4 Canada
Tel. (613) 567-3662
REMIND 2.3.0 (19 February 1991) Page 2
3. USING REMIND
The first thing you need to use REMIND is a reminder file. This
is a text file containing commands telling REMIND what to do.
Here's a sample reminder file:
# Sample file - by D. Skoll
BANNER Hi, Dave! Here are your reminders:
# First some birthdays
REM 6 Jan MSG David's birthday!
REM 23 Nov +10 MSG El's birthday is %a.
# Next some housekeeping stuff
REM 1 -1 OMIT sat sun RUN dobackup.bat
# Introduce some holidays
OMIT 25 dec # Christmas
OMIT 1 jul # Canada day
OMIT 22 nov 1990 # American thanksgiving
# Business things
REM 23 nov 1990 +2 AT 14:00 MSG %"Meeting with Bill%" \
at %2 %a.
Note that REMIND ignores blank lines and lines beginning with "#".
If the last character on a line is a backslash "\", then it is
treated as a continuation character and the next line is read.
You can string together several lines in this fashion, providing
the total length does not exceed 510 characters. Also, commands,
names of months, etc. can be typed in any mixture of upper- and
lower-case. The convention I use is to use upper case for REMIND
tokens like MSG, OMIT, etc. and mixed case for other words like
January and Sunday.
3.1. Running REMIND
To run REMIND, simply type:
REMIND rem_file
where rem_file is the name of the reminder file. The full form of
the REMIND command line is:
REMIND [-n | -d | -p | -c [-w -s]] [-vor] rem_file [date_spec]
Items in square brackets are optional. Note that you can use one
of the -d and -p options, but not both. The meanings of the
options are:
REMIND 2.3.0 (19 February 1991) Page 3
-n Next mode - in this mode, REMIND simply prints the next
occurrence of each reminder in a "Simple Calendar" format.
-d Debug mode - runs through the reminder file printing useful
information to the standard error stream.
-p Purge mode - purges expired reminders from the reminder file.
-c Calendar mode - this causes REMIND to produce a calendar for
the current month. If you supply a number n from 1 to 12
after the c (eg, -c6), then the calendar is produced for n
months.
-w When used with the -c option, specify the width of the
display device when producing a calendar. The default is -
w80; you can specify a different width. (Eg -w132 for a 132-
column printer.)
-s When used with the -c option, produce a "simple" calendar
listing rather than a formatted calendar. This is useful if
you wish to write a program which produces a "prettier"
calendar than the REMIND default.
-v Verbose mode - prints long error and debugging messages.
-o Ignore the 'ONCE' directives in the reminder file. (See the
section "Getting Reminded only Once per Day")
-r Ignore the 'RUN' directives in the reminder file. (See the
section "The RUN Keyword")
date_spec Run the reminder file as if the current date were the
specified date. This allows you to see what reminders
you'll get on a date in the future. This date must be
specified in full - for example, "6 July 1992" or "Dec
12 1999"
3.2. The REM Command
The most-used command in the reminder file is the REM command.
This command is used to denote a reminder. The form of the REM
command is:
REM [ONCE] [BEFORE | AFTER | SKIP] [date_spec] [delta] [back]
[repeat] [OMIT omit_list] [AT time [tdelta] [trepeat]] [UNTIL
expiry_date] <MSG | RUN> body
Note that these should all be on one line; the descriptions
unfortunately are too long to fit on one line. The components of
a REM command can appear in any order.
REMIND 2.3.0 (19 February 1991) Page 4
3.2.1. Date specifications
The date_spec consists of zero to four parts. These parts are DAY
(day of month), MONTH (month name), YEAR and WEEKDAY. MONTH and
WEEKDAY are the English names of months and weekdays. At least
the first three characters must be used. Case is irrelevant. The
following are examples of the various parts of a date
specification:
DAY: 1, 22, 31, 14, 3
MONTH: JANUARY, feb, March, ApR, may, june, Jul, August
YEAR: 1990, 1993, 2030, 95 (Interpreted as 1995)
The YEAR can range from 1990 to 2075.
WEEKDAY: Monday, tue, WED, Thu, Friday, saturday, sundAy
Note that there can be several WEEKDAY components separated by
spaces. The interpretation of date specifications is discussed
below.
The date specification is used by REMIND to compute a TRIGGER
DATE. The trigger date is the date on which a reminder will take
place. Here are examples of how trigger dates are computed:
1. Null date_spec. The reminder is triggered every day - the
trigger date is simply the system date.
2. Only DAY present. The reminder is triggered on the specified
day of each month. The trigger date is the closest such date
to the system date. For example:
REM 1 MSG Triggered on first of every month.
REM 31 MSG Triggered on 31st of every month with 31 days.
3. Only MONTH present: Triggered every day of the specified
month. Example:
REM feb MSG Triggered every day in February.
4. DAY and MONTH present. Examples:
REM 6 Jan MSG Triggered every 6th of January.
REM 29 Feb MSG Triggered every 29th of February.
5. YEAR present. Example:
REM 1990 MSG Triggered every day in 1990.
6. YEAR and DAY present. Examples:
REM 1 1990 MSG Triggered on first of every month in 1990.
REM 1991 23 MSG Triggered on 23rd of every month of 1991.
REMIND 2.3.0 (19 February 1991) Page 5
7. YEAR and MONTH present. Examples:
REM Feb 1990 MSG Triggered every day in February 1990.
REM 1991 September MSG Triggered every day in September 1991.
8. YEAR, MONTH and DAY present. Examples:
REM 8 January 1991 MSG Triggered on 8 Jan 1991 only.
REM 1992 March 9 MSG Triggered on 9 March 1991 only.
9. WEEKDAY only. Examples:
REM Saturday MSG Triggered every Saturday.
REM mon tue wed thu fri MSG Triggered every working day.
REM mon wed MSG Triggered every Monday and Wednesday.
10. WEEKDAY and DAY. Examples:
REM Sat 1 MSG Triggered on the first Saturday of each month.
REM Mon Tue Wed Thu Fri 15 MSG Triggered on the first working
day on or after the 15th of each month.
11. WEEKDAY and MONTH. Examples:
REM mon march MSG Triggered every Monday in March.
REM mon tue wed thu fri feb MSG Triggered every working day
in February.
12. WEEKDAY, MONTH and DAY. Examples:
REM mon 1 March MSG Triggered on the first Monday in March
REM sat sun 15 July MSG Triggered on the first Saturday or
Sunday on or after the 15th of July.
13. WEEKDAY and YEAR. Example:
REM sat sun 1991 MSG Triggered every Saturday and Sunday in
1991.
14. WEEKDAY, DAY and YEAR. Examples:
REM mon 15 1990 MSG First Monday after the 15th of every
month in 1990.
REM mon tue wed thu fri 1 1990 MSG First working dat of
every month in 1990.
15. WEEKDAY, MONTH and YEAR. Example:
REM Mon Wednesday 1991 Feb MSG Every Monday and Wednesday in
February 1991.
16. WEEKDAY, DAY, MONTH and YEAR. Example:
REM mon tue wed thu fri 28 Oct 1990 MSG First working day on
or after 28 October 1990.
REMIND 2.3.0 (19 February 1991) Page 6
Note that when WEEKDAY and DAY are specified, REMIND chooses the
first date on or after the specified DAY which also satisfies the
WEEKDAY constraint. It does this by picking the first date on or
after the specified DAY which is listed in the list of WEEKDAYs.
Thus, a reminder like
REM Mon Tue 28 Oct 1990 MSG Hi
would be issued only on Monday, 29 October, 1990. It would not be
issued on Tuesday, 30 October, 1990 since the 29th satisfies the
constraints.
3.2.2. Backward Scanning
Sometimes, you need to incorporate "backward scanning" into your
date specification. This is accomplished with the "back" part of
the reminder specification. If present, the back is specified as
a number preceded by one or two minus signs. (The distinction
between the "-x" and "--x" forms will be explained in "The OMIT
Command.") This causes REMIND to compute the trigger date and
then move back the specified number of days. For example:
REM Mon 1 --7 MSG The LAST Monday of every month.
This works by finding the first Monday of every month and then
moving "back" seven days. This results in the last Monday of the
previous month. Another example:
REM 1 -1 MSG The LAST day of every month.
Since we don't know how many days are in a month, to get to the
last day of a month, we go to the first day of the next month and
then move back one day.
Remind will automatically scan forwards and backwards until it
finds a trigger date meeting the criteria. Note that a back value
greater than 7 can lead to excessive backtracking and long
execution time.
3.2.3. Advance Warning
REMIND can warn you of an upcoming reminder as far in advance as
you desire. This is specified by a delta, which is a positive
number prefaced with one or two "+" signs. (The distinction
between the "+" and "++" forms will be explained in "The OMIT
Command") For example:
REM 8 Jan 1992 +3 MSG This reminder is emitted starting 3
days before January 8 1992.
REM 1 ++1 MSG This reminder is emitted on the first of every
month, as well as the last day of the preceding month.
REMIND 2.3.0 (19 February 1991) Page 7
In summary, a reminder with a delta is triggered on the usual
date, as well as all days preceding the trigger date by up to
"delta" days. This is useful for being reminded of birthdays well
in advance!
Deltas and backs can be combined:
REM Mon 1 -7 +3 MSG Emitted on the last Monday of every month
as well as the 3 days preceding it.
3.2.4. The MSG Keyword
The MSG keyword causes the remaining part of the line to be
printed to standard output when the reminder is triggered. The
line is first passed through a substitution routine before being
printed. See the section "Substitution" for details about
substitution.
3.2.5. The RUN Keyword
The RUN keyword causes the remaining part of the line to be passed
through the substitution routine, and then passed to the shell for
execution as if you had typed the command at the shell prompt.
3.2.6. Getting Reminded only Once per Day
In some situations, you only want a reminder emitted once per day.
This is useful if the reminder runs a program which should be run
only once. (Typically, such a reminder would have no delta.
Otherwise, the program would be run once for each day within the
delta preceding the trigger date.)
When REMIND finishes processing a file, it marks the modification
date of the file with the current system date. When it is run the
next time, if the file modification date and the system date are
the same, it ignores reminders which contain the ONCE keyword.
For example:
REM ONCE 1 Mon RUN do_backup
This reminder runs the program "do_backup" on the first Monday of
each month. It runs it only the first time REMIND is invoked. If
REMIND is subsequently invoked on the same day, this reminder is
ignored.
REMIND 2.3.0 (19 February 1991) Page 8
3.2.7. Locally Omitting Weekdays
A reminder containing the keyword OMIT followed by a list of
weekdays causes the delta and back to ignore the specified days
when moving backwards. This is called a "local omit." For
example:
REM 1 +1 OMIT sat sun MSG Hello there!
This reminder prints the message "Hello there!" on the first day
of each month, and the day before. If, however, the first day of
the month falls on a Sunday or Monday, the message is also issued
on the preceding Friday, since the delta does not count Saturday
and Sunday as it moves backwards.
REM 1 -1 +1 OMIT sat sun MSG Hi there!
This one issues a reminder on the last working day of each month,
as well as the preceding working day. Let's look at it in detail:
The "1" specifies the first of each month. The "back" of -1 tells
REMIND to go backwards by one day, not counting Saturday and
Sunday as it moves. This takes us to the last working day of the
preceding month. The delta of +1 ensures that the reminder will
be emitted on the day preceding this day also. Finally, if the
last working day of the month happens to be a Monday, the delta
combined with the local OMIT causes the reminder to be issued the
Friday before. Play around with deltas, backs and OMITs. They
can be very powerful and quickly become easy to understand.
3.2.8. Periodic Reminders
Sometimes reminders repeat periodically, where the repetition
period is a specific number of days. To create a repeating
reminder, use the "repeat" item, which is a number preceded by an
asterisk. (Example: *14) You supply a start date and the
repetition factor, and REMIND will trigger the reminder
periodically. Note that to use a repetition factor, you must
specify DAY, MONTH and YEAR in the date-spec. You can use
WEEKDAYS, deltas, backs and OMITS in the date-spec. However,
these are used ONLY in the calculation of the start date. Once
the start date has been calculated, OMITs are ignored and the
reminder is triggered in strict multiples of the period after the
start date.
For example, suppose you get paid every second Thursday, and that
8 November 1990 was a payday. You can be reminded of your payday
with this reminder:
REM 8 Oct 1990 +3 *14 MSG Payday is %b.
The delta of +3 means you'll be warned 3 days ahead of every
REMIND 2.3.0 (19 February 1991) Page 9
payday. The repeat of *14 means that the reminder will be
triggered every 14 days starting from 8 October 1990.
3.2.9. The AT Keyword
The AT keyword specifies a time for reminders which have times
associated with them. You should follow the AT keyword with a
time in 24-hour format, from 0:00 to 23:59. The tdelta and
trepeat items have the same format as delta and repeats for dates.
They are used in the UNIX version of REMIND to specify how many
minutes and over what interval to repeatedly pop up timed
reminders. These fields are accepted by the MS-DOS version of
REMIND, but do not serve any useful purpose. The AT keyword does,
however, cause reminders to be sorted by time when placed on the
calendar listing. Here are examples of how to use AT:
REM AT 17:00 MSG Work ends at %2!
REM 8 July 1991 AT 10:00 MSG Meeting with Bill %1.
3.2.10. The BEFORE, SKIP and AFTER Keywords
Normally, if a reminder falls on a holiday (see "The OMIT
Command"), the reminder is still issued. This can cause some
strange effects. Consider the following:
OMIT 25 Dec # Xmas Holiday
OMIT 1 Jan # New Year's Day
REM Tue MSG Departmental meeting.
The reminder "Departmental meeting" would be issued every
Tuesday, including 25 December, 1990, and 1 January, 1991, even
though those days are holidays. If, however, you use the SKIP
keyword:
REM SKIP Tue MSG Departmental meeting.
then the reminder would be issued every Tuesday, except on those
Tuesdays which happen to be holidays. The BEFORE keyword would
cause the reminder to be issued on Tuesdays, unless the Tuesday is
a holiday. In that case, the reminder would be issued the Monday
before. The AFTER keyword is similar, except that the reminder
would be issued on the Wednesday following any holidays occurring
on Tuesday.
In summary: The SKIP keyword causes reminder which happen to fall
on globally or locally omitted days not to be issued. The BEFORE
keyword moves reminders to the first non-omitted day prior to the
holiday. The AFTER keyword moves them to the first non-omitted
day after the holiday. Here are some examples:
REM AFTER 1 OMIT Sat Sun RUN Backup_on_first_working_day_of_month
REM SKIP Tue MSG Weekly Meeting
REMIND 2.3.0 (19 February 1991) Page 10
REM BEFORE 4 Dec 1991 *14 MSG Payday on every second Tuesday;\
Monday if that Tuesday happens to be a holiday.
3.3. The OMIT Command
In addition to being part of a REM command, the OMIT keyword can
act as a command in its own right. When used this way, it is
called a "global omit" and is used to specify holidays. The OMIT
command has two forms:
OMIT month day
OMIT year month day
The components can be in any order. For convenience, you can also
specify a DELTA and a RUN or MSG, as with the REM command. This
is used to avoid duplication. For example, the command:
OMIT 25 Dec +3 MSG %"Christmas%" is %a.
is exactly equivalent to:
OMIT 25 Dec
REM 25 Dec +3 MSG %"Christmas%" is %a.
The first format is used for holidays which fall on the same day
each year. For example:
OMIT 25 December # Christmas
OMIT 1 January # New year's day.
The second format is used for holidays which move from year to
year. For example:
OMIT 12 October 1990 # Columbus day 1990
OMIT 22 November 1990 # Thanksgiving day 1990
These dates are omitted by the "back" and "delta" portions of a
reminder, in addition to any local omits. For example:
OMIT 25 December
REM 26 +1 OMIT sat sun MSG Test2
This would issue the reminder on the 26th of each month, as well
as the working day preceding it. Also, on the 24th of December,
1990, the reminder would be issued. Even though Christmas 1990 is
on a Tuesday, the global OMIT would cause the delta to skip it.
Global OMITS are in force for all reminders following them in the
reminder file. Thus, you could have a series of reminders like
birthdays, etc. for which global omits may not be necessary. You
can then place the global holiday list in your file, followed by
REMIND 2.3.0 (19 February 1991) Page 11
business reminders for which omission of holidays would be
appropriate.
3.3.1. The "+" and "-" Forms vs "++" and "--"
The "+" and "-" forms of "back" and "delta" normally do not count
OMITted days when they count backwards. The is useful, for
example, to issue a reminder on the last working day of the month:
REM 1 -1 OMIT Sat Sun MSG Boo!
However, sometimes it is inconvenient to have the "back" and
"delta" skip OMITted days. For example, if you want a reminder on
the last Monday of every month regardless of any intervening
global OMITs, you can use:
REM 1 Mon --7 MSG Last Monday of month, for sure!
The "++" and "--" forms perform strict date subtraction, whereas
the "+" and "-" forms do not count locally and globally OMITted
days. One last example:
REM 1 Mon --7 AFTER MSG Last Monday of month, unless \
it's a holiday, in which case the following Tuesday.
3.4. The UNTIL Keyword
You can force a reminder to expire after a specified date by using
the UNTIL keyword followed by DAY, MONTH and YEAR in any order.
You can use this to create reminders of events which repeat over
an interval. For example, suppose you have jury duty from 25
February 1991 to 8 March 1991, not including weekends. Suppose
also that you wish to be warned starting on 22 February 1991. You
could use:
REM 25 Feb 1991 *1 ++3 OMIT Sat Sun SKIP UNTIL 8 Mar 1991 \
MSG Jury Duty %b.
The REPEAT of "*1" is necessary to have the reminder issued every
day during the interval. The "++3" provides advance warning; the
local OMIT combined with SKIP causes the weekends to be skipped,
and the UNTIL clause causes the reminder to expire on the
specified date.
Another example: Suppose you have a class every Wednesday until
29 May 1991. Use:
REM Wed UNTIL 29 May 1991 MSG Class!
REMIND 2.3.0 (19 February 1991) Page 12
3.5. The INCLUDE Command
The INCLUDE command takes the following form:
INCLUDE filename
This causes REMIND to suspend the current file and read the
contents of the specified filename. Once that file has been read,
REMIND continues reading the original file from the line after the
INCLUDE command. INCLUDEs can be nested to a maximum level of 10.
INCLUDE allows you or someone else to maintain a file of standard
holidays (global OMITS) or system-wide reminders that everyone
should get. For example, your local reminder file could look like
this:
# Example shown for MS-DOS
INCLUDE \etc\holidays.sys # System-wide holidays
INCLUDE \etc\remind.sys # Standard system-wide reminders
# Now my private reminders go here.
When you're PURGING a file (See the section "Purging Reminder
Files" ) only the top-level file is used for purging. Any
INCLUDEd files are read and processed, but not purged.
The ONCE keyword operates on the modification date of the top-
level file. The modification dates of INCLUDEd files are not used
to control the operation of the ONCE keyword.
3.6. Substitution
Before being processed, the body of a RUN or MSG command is run
through a substitution filter. This filter makes certain
substitutions in the body. The substitutions are marked by a '%'
symbol followed by a letter. Whenever these sequences occur, they
are replaced with text as determined below. All dates referred to
are the trigger date of the specified reminder.
%a * Replaced with "on WKDAY, DAY MONTH, YEAR"
For example, consider the reminder:
"REM 18 Oct 1990 +4 MSG Meeting with Bob %a."
If reminder were run on 16 October 1990, this would print:
"Meeting with Bob on Thursday, 18 October, 1990."
On 17 October 1990, the message would be:
"Meeting with Bob tomorrow."
On 18 October 1990, it would be:
"Meeting with Bob today."
REMIND 2.3.0 (19 February 1991) Page 13
%b * Replaced with "in DIFF days' time"
Example: "REM 18 Oct 1990 +4 MSG Meeting with Bob %b."
16 Oct 1990: "Meeting with Bob in 2 days' time."
17 Oct 1990: "Meeting with Bob tomorrow."
18 Oct 1990: "Meeting with Bob today."
Note that the number printed is the ACTUAL number of days
between the current date and the trigger date. The OMIT
lists have no effect on this number.
%c * Replaced with "on WKDAY"
Example: "REM 18 Oct 1990 +4 MSG Meeting with Bob %b."
16 Oct 1990: "Meeting with Bob on Thursday."
17 Oct 1990: "Meeting with Bob tomorrow."
18 Oct 1990: "Meeting with Bob today."
%d Replaced with the day of the month.
%e * Replaced with "on dd/mm/yyyy"
%f * Replaced with "on mm/dd/yyyy"
%g * Replaced with "on WKDAY, DAY MONTH"
%h * Replaced with "on dd/mm"
%i * Replaced with "on mm/dd"
%j * Replaced with "on WKDAY, MONTH DAYth, YEAR"
This is replaced with things of the form "on Monday, October
8th, 1990" or "on Sunday, October 21st, 1990" with the "st",
"nd", "rd", "th" as appropriate after the day of the month.
%k * Replaced with "on WKDAY, MONTH DAYth"
%l * Replaced with "on yyyy/mm/dd"
%m Replaced with the name of the month.
%n Replaced with the number (1 - 12) of the month.
%o Replaced with " (today)" if and only if the current system
date is the same as the date used by REMIND as the current
date. Recall that you can specify a date for REMIND to use
on the command line. This substitution is not generally
useful in a REMinder, but is useful in a BANNER statement.
See the section 'The BANNER Command'.
REMIND 2.3.0 (19 February 1991) Page 14
%p Replaced with "s" if the DIFF between the current date and
the trigger date is not 1. You can use this to construct
reminders like:
REM 1 Jan +4 MSG %x day%p to go before New Year's Day!
%q Replaced with "'s" if the DIFF between the current date and
trigger date is 1. Otherwise, replaced with "s'" This can
be used as follows:
REM 1 Jan +4 MSG New Year's Day in %x day%q time!
%r Replaced with the day of the month (01-31) with leading zero
if needed to pad to two digits.
%s Replaced with "st", "nd", "rd" or "th" depending on the day
of the month. Example:
REM 1 Mon +3 MSG First Monday of %m is the %d%s.
For October, 1990, this would print:
"First Monday of October is the 1st."
For November, 1990, it would print:
"First Monday of November is the 5th."
%t The number of the month (01 - 12) padded to two digits with
leading zero if necessary.
%u * Replaced with "on WKDAY, DAYth MONTH, YEAR"
This is the same as %a except "st", "nd", etc. is added to
the day of the month.
%v * Replaced with "on WKDAY, DAYth MONTH"
%w Replaced with "WKDAY", the name of the day of the week.
%x Replaced with the DIFF between the current date and the
trigger date. The DIFF is defined as the number of days
between the current date and the trigger date. OMITs are not
counted; strict date subtraction is performed.
%y Replaced with "YEAR", the year of the trigger date.
%z Replaced with "yy", the last two digits of the year.
%_ (Percent-underscore) replaced with a newline. You can use
this to achieve multi-line reminders.
REMIND 2.3.0 (19 February 1991) Page 15
%1 Replaced with "now", "m minutes from now", "m minutes ago",
"h hours from now", "h hours and m minutes from now", etc.,
as appropriate for a timed reminder. Note that timer
reminders are triggered like normal reminders - only the date
portion is considered. This causes the need for the "...ago"
forms.
%2 Replaced with "hh:mm" followed by "am" or "pm" as
appropriate.
%3 Replaced with "hh:mm", the AT time in 24-hour format.
%4 Replaced with "mm", where mm is the number of minutes between
"now" and the time specified by AT. If the AT time is
earlier than the current time, this number is negative.
%5 Replaced with "ma", where ma is the absolute value of the
number produced by %4.
%6 Replaced with "ago" or "from now", depending on the
relationship between the AT time and the current time.
%7 Replaced with the number of hours between the current time
and the AT time. This number is always non-negative.
%8 Replaced with the number of minutes between the current time
and the AT time, after the hours (%7) have been subtracted
out. This is a number from 0 to 59.
%9 Replaced with "s" if the number produced by "%8" is not 1.
%0 Replaced with "s" if the number produced by "%7" is not 1.
%! Replaced with "is" if the current time is before the AT time,
or "was" if it is after.
%" (percent-doublequote) is removed. This sequence is not used
by the substitution filter, but is used to tell REMIND which
text to include in a calendar entry when the -c option is
chosen. See the section "Producing a Calendar"
Notes:
o REMIND normally prints a blank line after each reminder.
However, if the last character of the body is "%", then the
blank line will not be printed.
o All substitution sequences marked with "*" are replaced with
"today" if the current date equals the trigger date, or
"tomorrow" if the trigger date is one day after the current
date.
o Any of the substitutions dealing with time (0 though 9 and
REMIND 2.3.0 (19 February 1991) Page 16
"!") produce undefined results if used in a reminder without
the AT keyword. Also, if a reminder has a delta and may be
triggered on several days, the time substitutions ignore the
date. Thus, the "%1" substitution may report that a meeting
is in 15 minutes, for example, even though it may only be in
2 days time. It is recommended that you use the "%1"
substitution only on reminders with no delta.
o Capital letters can be used, in which case the first letter
of the substituted text is capitalized.
o All other characters following a "%" sign are simply copied.
In particular, to get a "%" sign out, use "%%" in the body.
To start a body with a space, use "% " since REMIND normally
scans for the first non-space character after the MSG or RUN
token.
3.7. Producing a Calendar
REMIND can be used to create a calendar based on the contents of
your reminder file. This is done by invoking REMIND with the -c
option.
When you produce a calendar, REMIND will pass the text through the
substitution mechanism. In addition, you may indicate to REMIND
which portions of the text should be placed in the calendar. This
is done with the %" sequence. Here's an example:
REM 6 Jan +6 MSG %"David's birthday%" is %a.
When you run REMIND normally, it triggers the reminder as if the
%" sequences were not there. When you produce a calendar with the
-c option, however, only the text "David's birthday" is placed
into the calendar. For convenience, timed reminders are sorted by
time before being entered into the calendar, and the time of each
reminder is printed before the text.
Note that only MSG reminders are included in the calendar; RUN
reminders are ignored. However, if you explicitly indicate text
in a RUN reminder with %" signs, it will be placed in the
calendar. If you indicate empty text for the calendar entry with
the sequence %"%" in the reminder body, then the reminder will be
ignored when producing the calendar.
3.8. The BANNER Command
When REMIND issues reminders, it normally prints a message saying:
"Reminders for WKDAY, DAYth MONTH, YEAR (today):"
if it is running with the current date equal to the system date.
If it is running with a different date supplied via the command
line, it leaves out the " (today):"
REMIND 2.3.0 (19 February 1991) Page 17
You can change this default to anything you want with the BANNER
command. It should appear in the reminder file before any REM
commands. (This is not enforced, but a BANNER command encountered
after a reminder has been issued will be ignored.)
The format of BANNER is: BANNER string
The string is passed through the substitution mechanism described
above, using the current date for substitution. The standard
banner is described by:
BANNER Reminders for %w, %d%s %m, %y%o:
You can have a blank banner by using:
BANNER %
3.9. Controlling the OMIT Context
Sometimes, you INCLUDE files which add global OMITs that you don't
need or want. Other times, you need to introduce a global OMIT
for one peculiar reminder, but don't want it for other reminders.
Three commands allow you to insulate changes in the OMIT context
between reminders.
CLEAR-OMIT-CONTEXT will discard all global OMITs and start you out
with a clean slate.
PUSH-OMIT-CONTEXT will save all the global OMITs onto an internal
stack and leave the current context unchanged.
POP-OMIT-CONTEXT will restore the OMIT context saved by the last
PUSH-OMIT-CONTEXT.
Here's an example - suppose you have a block of reminders or an
include file which expects to start out with no global OMITs.
Suppose that it introduces global OMITs which you don't want to
affect any of your other reminders. Here's how to achieve this:
# blah blah blah
PUSH-OMIT-CONTEXT # Save for later
CLEAR-OMIT-CONTEXT # Start out with clean slate
# Put block or INCLUDE file here
POP-OMIT-CONTEXT # Get back the OMITs - now the effects
# of the block or INCLUDE file are gone.
REMIND 2.3.0 (19 February 1991) Page 18
4. PURGING REMINDER FILES
You should periodically purge your reminder file of "expired" REM
commands and OMITs. These are reminders which took place in the
past and can never happen again, or OMITs which are for past
years. Of course, only REMs and OMITs with the YEAR specified can
ever expire.
To purge your file, run REMIND in purge mode. This mode simply
echoes non-expired lines to standard output, and expired lines to
standard error. Thus, to purge a file, you could type:
REMIND -p notes.old > notes.new
The file "notes.new" would contain all non-expired lines from
notes.old. All expired lines would be echoed to the screen.
INCLUDEd files are read and processed, but are not purged. You
must purge each INCLUDEd file separately.
Note that reminders which do not specify a YEAR, as well as
repeating reminders, can never expire.
You can supply a date on the command line when purging, but
beware: If you supply a date in the future, you may inadvertantly
purge lines which have not really expired yet.
5. DEBUGGING YOUR REMINDER FILE
The debug flag (-d) is used to debug reminder files (not the
REMIND program!) It tells you all sorts of useful information
about the reminder file. It displays the trigger date of each
reminder, and places an asterisk by those which would be issued on
the current date. It also informs you of OMITs which have
expired, and gives several warnings about situations which could
lead to long execution time or unexpected results.
If you have a long reminder file, you may want to redirect the
standard error stream. In Unix, this is accomplished easily. In
MS-DOS, you can use the E2O program supplied with REMIND.
5.1. Format of Debugging and Error Messages
REMIND prints the filename, followed by the line number in
brackets, followed by the error or debugging message. If the
verbose flag (-v) is supplied, it echoes the line from the file as
well.
REMIND 2.3.0 (19 February 1991) Page 19
6. WISH LIST
o REMIND has been ported to Unix. The source has been posted
on alt.sources and comp.sources.misc on the usenet. It's
also available in the file pub/remind-2.3.0.tar.Z via
anonymous ftp from alfred.ccs.carleton.ca (134.117.1.1)
o Faster algorithms for date calculation. Most of the
algorithms are fairly "brute force", but they execute
reasonably quickly. The "back" feature especially leads to a
lot of backtracking.
o A prettier interface - maybe some snazzy pop-up windows, with
centered messages, colors and so on... well, if you really
want that, use REMIND as a back-end and do some post-
processing on its output. Easy from Unix, slow from MS-DOS.
o Automatic purging of reminder files. Could be useful or
dangerous, depending on your perspective.
7. WISHES LIST
I hope you enjoy using REMIND. If you have any suggestions,
comments, bugs, problems, donations :-) or kudos, send them to:
David Skoll
4-317 Lebreton Street
Ottawa, Ontario
K1S 4L4 CANADA
Tel. (613) 567-3662
I can be reached by e-mail at dfs@doe.carleton.ca.
REMIND 2.3.0 (19 February 1991) Page 20
